个人网站 (Mkdocs)

在使用 MkDocs 构建笔记网站时，项目根目录下的这些文件和文件夹各有其用途。下面逐一解释，并重点说明 .gitignore 的作用。

Github Pages 网页搭建 ¶

文件 / 文件夹作用详解 ¶

.github/¶

• 用途：存放与 GitHub 相关的自动化配置，最常用的是 GitHub Actions 工作流文件（位于 .github/workflows/）。
• 在 MkDocs 项目中的典型作用：可以配置自动构建和部署网站到 GitHub Pages。例如，当推送到 main 分支时，自动运行 mkdocs build 并将生成的 site/ 目录发布到 gh-pages 分支，实现持续部署。

archive/¶

• 用途：通常是用户自定义的文件夹，用于存放归档的旧笔记或不再维护的文档。
• 在 MkDocs 项目中的常见做法：如果你想把一些旧内容保留在仓库中但不希望它们出现在网站导航里，可以放在这里，并在 mkdocs.yml 中排除该目录，或者通过链接手动引用。

docs/¶

• 用途：MkDocs 默认的源文件目录。里面存放所有的 Markdown 文件（即你的笔记内容）以及可能用到的图片、附件等。
• 说明：MkDocs 会扫描此目录下的 .md 文件，根据 mkdocs.yml 中的配置生成对应的 HTML 页面。你可以在此目录下自由组织子文件夹来分类笔记。

.gitignore¶

• 用途：Git 的忽略文件，告诉 Git 不要将某些文件或目录纳入版本控制。
• 内容解读：你看到只有一行 /site，它的含义是忽略根目录下的 site 文件夹（/ 表示从仓库根目录开始）。
• 为什么忽略 site/？
  在 MkDocs 中，执行 mkdocs build 或 mkdocs serve 后，会在根目录生成一个 site/ 文件夹，里面存放构建好的静态网站文件（HTML、CSS、JS 等）。这些文件是根据源文件自动生成的，不需要提交到 Git 仓库，因为任何人克隆仓库后都可以通过 mkdocs build 重新生成。忽略它们可以避免仓库臃肿，并减少无意义的提交变动。

LICENSE¶

• 用途：项目的许可证文件。例如 MIT、GPL 等，规定了他人使用、修改、分发你的代码 / 内容的权利。如果你的笔记开源，通常会包含此文件。

mkdirs.yml —— 可能是mkdocs.yml ¶

• 用途：这很可能是 MkDocs 的主配置文件，默认文件名应为 mkdocs.yml。
• 作用：配置网站的站点名称、主题、导航结构、插件、扩展等。例如：

site_name: 我的笔记
theme: material
nav:
  - 首页: index.md
  - 教程: tutorial/

README.md¶

• 用途：项目的说明文档，通常展示在 GitHub 仓库主页。可以介绍这个笔记仓库的用途、如何使用、如何本地构建等。

总结 ¶

• .gitignore 中的 /site 是标准的 MkDocs 项目配置，用于避免将生成的静态网站文件提交到 Git，保持仓库干净。
• 其他文件夹和文件共同构成了一个完整的 MkDocs 笔记项目：源文件在 docs/，配置文件在 mkdocs.yml，自动化部署在 .github/，归档内容放在 archive/，许可证和说明文档也一应俱全。

具体制作流程与个性化设计，参考 https://squidfunk.github.io/mkdocs-material/